Skip to main content

常见问题

本页汇总 V1/V2 接口对接过程中的常见问题。V3 接口的字段与调用约定，请优先查阅对应接口页面。

一、开发者与凭证​

1. 如何成为开发者？​

账号注册与凭证申请在 V1、V2、V3 之间完全一致，统一由 OpenAPI V3 快速开始 维护，本页不再重复步骤。完整流程包含三步：

  1. 邀请注册高仙开发者：组织内邀请，或由管理员在 IAM 客户中心代管理其他组织。
  2. 激活开发者账号：按激活邮件完成激活；已有账号需要补充角色时，由用户管理员在 IAM 用户管理中编辑角色。
  3. 创建 AccessKey：在开发者中心「我的 AccessKey」创建，同时获得 AccessKeyID、AccessKeySecret、ClientID 和 ClientSecret。
应用管理已停止使用

原「应用管理」不再用于创建应用。新建 AccessKey 时系统会自动生成应用信息，无需再单独创建应用。

二、接口权限​

2. 为什么获取机器人列表返回的机器人和账号绑定的不一致？​

账号绑定的机器人属于个人账号与机器人的关系；通过接口获取的机器人属于客户与机器人的关系，两者不是同一套关系。

获取机器人接口路径：/openapi/v1alpha1/RobotService_ListRobots

  • relation 传值 contract：获取合同客户下的机器人。
  • relation 传空：获取终端客户下的机器人。
  • relation 传值 cugrup：获取集团下的机器人。适用于运维商服务的机器存在多个终端客户的场景，需提前联系高仙升级集团。

三、机器人控制​

3. 控制机器前，为什么先获取机器人状态？​

如果要向机器人发出指令，请先获取机器人的实时状态，再根据实时状态数据发出指令。例如，不能使用两小时前的机器人状态来发出指令；如果机器人本身已经移动或状态发生变化，可能存在安全风险。

控制机器前先获取机器人状态

4. 机器人任务下发，哪个接口？​

按机型与软件版本区分：

  1. 非 S 机器且软件版本早于 AIO：openapi/v1alpha1/robots/{robot}/commands/{command}
  2. S 线机型且现场未部署站点，无站点任务启动 API：
    • 接口路径：/openapi/v2alpha1/robotCommand/tempTask:send
    • areaID：1-255 任意传值，属于历史设计问题。
  3. S 线机器或已升级 AIO 版本的机器，站点任务下发：openapi/v2alpha1/site/submitTask

任务下发接口

5. 机器人状态返回值有哪些？​

接口路径：openapi/v1alpha1/robots/{robot}/status

taskState 只有 4 个返回值：空闲、执行中、任务暂停、其他。暂无导航相关状态开放。

机器人状态字段

6. 部署梯控的现场，如何实时获取当前机器人所在楼层？​

建议调整地图命名方式，建立地图名称与楼栋、楼层的对应关系，通过机器人当前所在地图间接得知所在楼栋和楼层。

7. 云平台状态延时参考，如何查询正在执行的任务？​

延时参考为 30 秒；若增加任务自检，延时参考建议为 60 秒。

M 线查询正在执行的任务：openapi/v1alpha1/robots/{robot}/status → executingTask

查询正在执行的任务

8. 有时候获取或批量获取机器人的实时状态数据，会出现无数据的情况？​

请先确认机器人是否在线。如果机器人正常在线，请联系我们的工程师检查软件版本，部分数据需要特定机器人版本才会上报。

无状态数据

9. 机器人位置地图，其坐标是：角度、x、y 坐标吗？​

是的。如果 111 和环卫车配有 GPS 模块，还会提供额外的 GPS 数据。GPS 数据的精度（小数点位数）直接来自机器人，与机器人搭载的 GPS 型号有关。

位置坐标

四、任务报告​

10. 生成机器人任务报告图片（GenerateRobotTaskReportPng）的任务报告 ID 从哪里来？如何设置 languageCode？​

任务报告 ID 从 ListRobotTaskReports 接口获取，接口来源：openapi/v2alpha1/robots/*/taskReports

languageCode 采用 IETF 语言标签，参考 IETF language tag。

任务报告 ID 来源

11. 是否支持按照某个时间段获取任务报告？​

暂不支持。

12. 为什么获取今日的任务报告为空？​

任务报告上报需要机器人联网。若机器人网络不佳或离线，报告可能无法在当天收到。例如 6 月 1 日执行任务，6 月 2 日设备才联网上传，那么 6 月 1 日的任务报告只能在 6 月 2 日之后获取。

五、数据推送​

13. incident push 对接​

  1. 由客户的高仙对接人（一般是解决方案经理）创建 Jira，提交给产研。
  2. Jira 中需包含客户提供的信息：目标语言、URL、appID。

incident push 对接

14. 任务报告数据推送对接​

  1. 由客户的高仙对接人（一般是解决方案经理）创建 Jira，提交给产研。
  2. Jira 中需包含客户提供的信息：URL、appID。

任务报告推送对接

六、其他​

15. 为什么接口无法调试 / 接口不返回数据？​

请依次检查：

  • 接口路径是否正确。
  • POST / GET 方法是否正确。
  • 请求参数格式是否正确。

16. 如何确认机器的数据是否上报？​

需要到对应环境的时序数据库中查询。库名为物模型的 productKey，deviceId 由机器人生成。

时序数据库查询

17. GAS API 和 Gaussian Open API 的域名是？​

https://openapi.gs-robot.com/

18. openAPI 所有分页查询接口的 page size 限制​

当前限制为 200，涉及的接口如下（统计截至 2024/05/20）：

分页限制涉及的接口